# Languine SDK Documentation

The Languine SDK provides a simple and powerful way to integrate Languine's translation capabilities into your applications.

## Installation

```bash
npm install @languine/sdk
```

## Quick Start

```typescript
import { Languine } from "@languine/sdk";

async function run() {
  const languine = new Languine({
    apiKey: process.env.LANGUINE_API_KEY,
  });

  const result = await languine.translate({
    sourceText: "Hello, world!",
    sourceLocale: "en",
    targetLocale: "sv",
    projectId: process.env.LANGUINE_PROJECT_ID,
  });

  console.log(result.translatedText);
}

run();
```

## Authentication

The SDK requires an API key to authenticate requests. Your API key should start with `org_`. You can obtain an API key from your Languine dashboard.

```typescript
const languine = new Languine({
  apiKey: process.env.LANGUINE_API_KEY,
});
```

**Parameters:**

The `translate` method accepts an object with the following properties:

- `projectId` (string, required): The ID of your Languine project
- `sourceLocale` (string, required): The locale code of the source text
- `targetLocale` (string, required): The locale code to translate into
- `sourceText` (string, required): The text to translate
- `format` (string, optional): The format of the source text. Defaults to "string"
- `cache` (boolean, optional): Whether to use cached translations. Defaults to true

**Supported Formats:**

- `string`: Plain text
- `json`: JSON files
- `yaml`: YAML files
- `properties`: Java properties files
- `android`: Android resource files
- `xcode-strings`: iOS Strings files
- `xcode-stringsdict`: iOS Stringsdict files
- `xcode-xcstrings`: iOS XCStrings files
- `md`: Markdown files
- `mdx`: MDX files
- `html`: HTML files
- `js`: JavaScript files
- `ts`: TypeScript files
- `po`: Gettext PO files
- `xliff`: XLIFF files
- `csv`: CSV files
- `xml`: XML files
- `arb`: ARB (Application Resource Bundle) files
- `ftl`: Fluent FTL files
- `php`: PHP files

## Best Practices

1. **Cache Management**: By default, translations are cached. You can disable caching for specific requests by setting `cache: false` in the translate parameters.

2. **Error Handling**: Always implement proper error handling in your application to gracefully handle API errors.

3. **API Key Security**: Never expose your API key in client-side code. Always keep it secure on your server.

4. **Format Selection**: Choose the appropriate format for your content type to ensure accurate translations.

## Examples

### Translating JSON Content

```typescript
const languine = new Languine({
  apiKey: process.env.LANGUINE_API_KEY,
});

const jsonContent = {
  greeting: "Hello",
  farewell: "Goodbye"
};

const translation = await languine.translate({
  projectId: 'your_project_id',
  sourceLocale: 'en',
  targetLocale: 'fr',
  sourceText: JSON.stringify(jsonContent),
  format: 'json'
});

const translatedJson = JSON.parse(translation.translatedText);
```

### Translating Markdown Content

```typescript
const languine = new Languine({
  apiKey: process.env.LANGUINE_API_KEY,
});

const markdownContent = "# Welcome\n\nThis is a **markdown** document.";

const translation = await languine.translate({
  projectId: 'your_project_id',
  sourceLocale: 'en',
  targetLocale: 'de',
  sourceText: markdownContent,
  format: 'md'
});

console.log(translation.translatedText);
```
